Expand description
This library defines strings with copy-on-write semantics.
§CowStr
Is a String that can be initialized to a static string or be build dynamically. Its contents can then be immutably shared and reference counted. When mutation is required the string will be copied first.
This resembles a improved Arc<Cow<'static, str>>
with some differences:
- No double dereference going from
Arc
toString
to the actual data. - There are no
Weak
references. CowStr
can be interior-mutable extended (append at the end).- Improved
AllocationStrategy
CowStr
implements many of the std::String
methods. Missing methods will be added as required,
PR’s are welcome.
§SubStr
Refers to an immutable slice inside of a CowStr
. This somewhat resembles the String
/&str
relationship while SubStr
keeping a strong reference to its orgin CowStr
and thus don’t
need lifetimes.
§Features
- serde wrapping the default string (de)serialization.
- nightly enable some nightly optimizations and extensions
§Implementation Notes
CowStr
is made for sharing immutable strings, a short single CowStr
will occupy slightly
more memory than a std String
. But as soon a CowStr
is cloned or SubStr
’s are used
it pays back. Especially since SubStr
don’t need lifetimes as they use reference counting
memory management becomes significantly easier.
Because rust has yet incomplete support for DST’s CowStr
needs some unsafe code. This is
liberally chosen, when possible contracts are enforced by debug_assert
’s.
§Testing
CowStr
commes with an extensive test suite. ‘cargo-mutants’ is used to detect missing
tests. Releases must pass testing under ‘miri’.
Macros§
- Creates a
CowStr
using interpolation of runtime expressions.
Structs§
- A shared string that is copy-on-write and can be either static or dynamic shared with a reference counter. When a
CowStr
is dynamically created it can be mutated until it becomes cloned, then mutation becomes copy-on-write as marked with copy-on-write below. - The
CowStrPushGuard
implements thetry_push*
methods which allow to extend aCowStr
in place. - Arbitrary immutable text as span from some shared string.
SubStr
holding a reference to theCowStr
they lie within. This removes the need to pass lifetimes around as memory become reference counted.
Enums§
- The errors that the
CowStr
API may return.
Constants§
- A constant for an always empty
SubStr
. - The alignment/size granularity a
CowStr
allocated memory block. This is mostly a implementation detail. To avoid tiny allocations and memory fragmentation allocated lengths are a multiple of this alignment. Note that an allocation includes a header. - The size of the header of a
CowStr
allocated memory block. This is mostly a implementation detail but it is exported to give the user more control about memory allocations.CowStr::with_capacity(65536 - cowstr::RCSTRING_HEADER_SIZE)
will allocate aCowStr
that uses exactly 64kb memory.
Traits§
- A trait for converting a value to a
CowStr
. - A trait for converting a value to a
SubStr
.